/*
 * $Id: QEADIFElement.h 68 2009-06-10 14:48:35Z jon@bway.net $
 * Chalk
 *
 * Created 6/4/09
 * Copyright Jon Gordon
 * 
 * Permission is hereby granted, free of charge, to any person obtaining 
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including 
 * without limitation the rights to use, copy, modify, merge, publish, 
 * distribute, sublicense, and/or sell copies of the Software, and to 
 * permit persons to whom the Software is furnished to do so, subject to 
 * the following conditions:
 * 
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#import <Foundation/Foundation.h>

typedef enum {
    qeADIFElementComment = 1,
    qeADIFElementEOI =     2,
    qeADIFElementError =   3,
    qeADIFElementField =   4,
    qeADIFElementTag =     5
} QEADIFElementTypeCode;

/**
 * Class representing a single ADIF element identified by the parser.
 * For this purpose, an ADIF element element is one of the following:
 *
 *  1)  An ADIF data field, including field name *and* its data.
 *
 *  2)  An ADIF tag, which, syntactically, looks like a data field, but
 *      without any data.  Examples include <eoh>, <eor>, and ARRL's
 *      nonstandard <APP_LoTW_EOF>.
 *
 *  3)  A comment, which, in ADIF, means any text not specifically
 *      included in an ADIF data field.
 *
 *  4)  EOI, signifying that the parser has reached the end of the input
 *      data.
 *
 *  5)  An error.
 *
 * The parser's output is a stream of these elements, corresponding to
 * the representation of the data in the source supplied to the parser.
 * These elements are organized into ADIF headers and records in an
 * ADIF file (QEADIFFile), which uses instances of QEADIFDataField to
 * represent the actual data.
 */
@interface QEADIFElement : NSObject {
@private
    NSUInteger line;
    NSUInteger position;
    BOOL comment;
    NSString *fieldName;
    unichar typeCode;
    NSString *fieldValue;
    NSString *src;
    NSError *error;
}

@property(nonatomic) NSUInteger line;
@property(nonatomic) NSUInteger position;
@property(nonatomic, retain) NSString *fieldName;
@property(nonatomic) unichar typeCode;
@property(nonatomic, retain) NSString *fieldValue;
@property(nonatomic, retain) NSString *src;
@property(nonatomic, retain) NSError *error;

+ (QEADIFElement *)elementTagWithFieldName:(NSString *)newFieldName 
                                fromSource:(NSString *)newSrc 
                                    atLine:(NSUInteger)newLine 
                               andPosition:(NSUInteger)newPos;
+ (QEADIFElement *)elementFieldWithFieldName:(NSString *)newFieldName
                                  fieldValue:(NSString *)newFieldValue
                                  fromSource:(NSString *)newSrc 
                                      atLine:(NSUInteger)newLine 
                                 andPosition:(NSUInteger)newPos;
+ (QEADIFElement *)elementFieldWithFieldName:(NSString *)newFieldName
                                  fieldValue:(NSString *)newFieldValue
                                      ofType:(unichar)newFieldTypeCode
                                  fromSource:(NSString *)newSrc 
                                      atLine:(NSUInteger)newLine 
                                 andPosition:(NSUInteger)newPos;
+ (QEADIFElement *)elementError:(NSError *)newError
                     fromSource:(NSString *)newSrc 
                         atLine:(NSUInteger)newLine 
                    andPosition:(NSUInteger)newPos;
+ (QEADIFElement *)elementCommentFromSource:(NSString *)newSrc 
                                     atLine:(NSUInteger)newLine 
                                andPosition:(NSUInteger)newPos;
+ (QEADIFElement *)elementEOIAtLine:(NSUInteger)newLine 
                        andPosition:(NSUInteger)newPos;

// for any instance of QEADIFElement, exactly ONE one of these
// five methods will return YES, and the others will return NO.
- (BOOL)isComment;
- (BOOL)isEOI;
- (BOOL)isError;
- (BOOL)isField;
- (BOOL)isTag;

- (QEADIFElementTypeCode)elementType;

- (NSString *)description;
@end
